using Admin.Application.Common;
using Admin.Application.Dto;
using Admin.Application.Dto.Role;

namespace Admin.Application.Repositories;

/// <summary>
/// 角色服务接口，提供角色相关的业务逻辑操作。
/// </summary>
public interface IRoleService
{
    /// <summary>
    /// 添加一个新的角色。
    /// </summary>
    /// <param name="roleDto">角色的数据传输对象，包含角色的基本信息。</param>
    /// <returns>
    /// 返回一个 <see cref="Result{T}"/> 对象，其中包含操作结果。
    /// - 成功时，返回包含成功消息的 <see cref="Result{T}"/>。
    /// - 失败时，返回包含错误消息的 <see cref="Result{T}"/>。
    /// </returns>
    Task<Result<string>> AddRoleAsync(RoleDto roleDto);

    /// <summary>
    /// 删除一个角色。
    /// </summary>
    /// <param name="roleId">要删除的角色的唯一标识符。</param>
    /// <returns>
    /// 返回一个 <see cref="Result{T}"/> 对象，其中包含操作结果。
    /// - 成功时，返回包含成功消息的 <see cref="Result{T}"/>。
    /// - 失败时，返回包含错误消息的 <see cref="Result{T}"/>。
    /// </returns>
    Task<Result<string>> DeleteRoleAsync(Guid roleId);

    /// <summary>
    /// 更新一个角色的信息。
    /// </summary>
    /// <param name="roleId">要更新的角色的唯一标识符。</param>
    /// <param name="roleDto">包含更新后角色信息的数据传输对象。</param>
    /// <returns>
    /// 返回一个 <see cref="Result{T}"/> 对象，其中包含操作结果。
    /// - 成功时，返回包含成功消息的 <see cref="Result{T}"/>。
    /// - 失败时，返回包含错误消息的 <see cref="Result{T}"/>。
    /// </returns>
    Task<Result<string>> UpdateRoleAsync(Guid roleId, RoleDto roleDto);

    /// <summary>
    /// 异步更新角色启用状态。
    /// </summary>
    /// <param name="roleId">要更新的角色的ID。</param>
    /// <param name="ActiveDto">包含更新信息的角色数据传输对象（DTO）。</param>
    /// <returns>一个包含操作结果的 Task 对象，成功时返回 Result<string>; 类型的成功消息，失败时返回错误消息。</returns>
    Task<Result<string>> UpdateIsActive(Guid userId, ActiveDto activeDto);

    /// <summary>
    /// 获取分页的角色列表。
    /// </summary>
    /// <param name="pageIndex">分页的页码，从 1 开始。</param>
    /// <param name="pageSize">每页显示的角色数量。</param>
    /// <returns>
    /// 返回一个 <see cref="Result{T}"/> 对象，其中包含分页的角色列表。
    /// - 成功时，返回包含角色列表的 <see cref="Result{T}"/>。
    /// - 失败时，返回包含错误消息的 <see cref="Result{T}"/>。
    /// </returns>
    Task<Result<List<ResRoleDto>>> GetPagedRoleAsync(int pageIndex, int pageSize);

    /// <summary>
    /// 根据角色 ID 获取角色的详细信息。
    /// </summary>
    /// <param name="roleId">角色的唯一标识符。</param>
    /// <returns>
    /// 返回一个 <see cref="Result{T}"/> 对象，其中包含角色的详细信息。
    /// - 成功时，返回包含角色信息的 <see cref="Result{T}"/>。
    /// - 失败时，返回包含错误消息的 <see cref="Result{T}"/>。
    /// </returns>
    Task<Result<ResRoleDto?>> GetRoleByIdAsync(Guid roleId);

    /// <summary>
    /// 为角色分配权限。
    /// </summary>
    /// <param name="roleId">角色的唯一标识符。</param>
    /// <param name="permissionId">要分配的权限的唯一标识符。</param>
    /// <returns>
    /// 返回一个 <see cref="Result{T}"/> 对象，其中包含操作结果。
    /// - 成功时，返回包含成功消息的 <see cref="Result{T}"/>。
    /// - 失败时，返回包含错误消息的 <see cref="Result{T}"/>。
    /// </returns>
    Task<Result<string>> AssignPermissionsToRoleAsync(Guid roleId, Guid permissionId);

    /// <summary>
    /// 从角色中移除权限。
    /// </summary>
    /// <param name="roleId">角色的唯一标识符。</param>
    /// <param name="permissionId">要移除的权限的唯一标识符。</param>
    /// <returns>
    /// 返回一个 <see cref="Result{T}"/> 对象，其中包含操作结果。
    /// - 成功时，返回包含成功消息的 <see cref="Result{T}"/>。
    /// - 失败时，返回包含错误消息的 <see cref="Result{T}"/>。
    /// </returns>
    Task<Result<string>> RemovePermissionsFromRoleAsync(Guid roleId, Guid permissionId);
}